TypeScript Web API: Uppnå typsäkerhet med Fetch för robusta applikationer

I modern webbutveckling är hämtning av data från API:er en fundamental uppgift. Även om det inbyggda Fetch API:et i JavaScript erbjuder ett bekvämt sätt att göra nätverksanrop, saknar det inneboende typsäkerhet. Detta kan leda till exekveringsfel (runtime errors) och göra det utmanande att underhålla komplexa applikationer. TypeScript, med sina statiska typningsmöjligheter, erbjuder en kraftfull lösning på detta problem. Denna omfattande guide utforskar hur man implementerar typsäkerhet med Fetch API i TypeScript för att skapa mer robusta och underhållbara webbapplikationer.

Varför typsäkerhet är viktigt med Fetch API

Innan vi dyker in i implementationsdetaljerna, låt oss förstå varför typsäkerhet är avgörande när man arbetar med Fetch API:

• Minskade exekveringsfel: TypeScripts statiska typning hjälper till att fånga fel under utvecklingen, vilket förhindrar oväntade problem vid körning orsakade av felaktiga datatyper.
• Förbättrad kodunderhållbarhet: Typannoteringar gör koden lättare att förstå och underhålla, särskilt i stora projekt med flera utvecklare.
• Förbättrad utvecklarupplevelse: IDE:er ger bättre autokomplettering, felmarkering och refaktoriseringsmöjligheter när typinformation finns tillgänglig.
• Datavalidering: Typsäkerhet gör det möjligt för dig att validera strukturen och typerna av data som tas emot från API:er, vilket säkerställer dataintegritet.

Grundläggande användning av Fetch API med TypeScript

Låt oss börja med ett grundläggande exempel på hur man använder Fetch API i TypeScript utan typsäkerhet:

            async function fetchData(url: string) {
  const response = await fetch(url);
  const data = await response.json();
  return data;
}

fetchData('https://api.example.com/users')
  .then(data => {
    console.log(data.name); // Potentiellt exekveringsfel om 'name' inte existerar
  });

            

              
                Copy
              
            
          

I detta exempel hämtar funktionen `fetchData` data från en given URL och parsar svaret som JSON. Typen för variabeln `data` är dock implicit `any`, vilket innebär att TypeScript inte kommer att erbjuda någon typkontroll. Om API-svaret inte innehåller egenskapen `name` kommer koden att kasta ett exekveringsfel.

Implementera typsäkerhet med gränssnitt (Interfaces)

Det vanligaste sättet att lägga till typsäkerhet till Fetch API-anrop i TypeScript är genom att definiera gränssnitt som representerar strukturen för den förväntade datan.

Definiera gränssnitt

Låt oss säga att vi hämtar en lista över användare från ett API som returnerar data i följande format:

            [
  {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane.smith@example.com"
  }
]

            

              
                Copy
              
            
          

Vi kan definiera ett gränssnitt för att representera denna datastruktur:

            interface User {
  id: number;
  name: string;
  email: string;
}

            

              
                Copy
              
            
          

Använda gränssnitt med Fetch API

Nu kan vi uppdatera funktionen `fetchData` för att använda `User`-gränssnittet:

            async function fetchData(url: string): Promise {
  const response = await fetch(url);
  const data = await response.json();
  return data as User[];
}

fetchData('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.name); // Typsäker åtkomst till egenskapen 'name'
    });
  });

            

              
                Copy
              
            
          

I detta uppdaterade exempel har vi lagt till en typannotering till funktionen `fetchData`, som specificerar att den returnerar ett `Promise` som resolverar till en array av `User`-objekt (`Promise`). Vi använder också en typassertion (`as User[]`) för att tala om för TypeScript att datan som returneras av `response.json()` är en array av `User`-objekt. Detta hjälper TypeScript att förstå datastrukturen och erbjuda typkontroll.

Viktigt att notera: Även om nyckelordet `as` utför en typassertion, utför det inte validering vid körning. Det talar om för kompilatorn vad den ska förvänta sig, men det garanterar inte att datan faktiskt matchar den angivna typen. Det är här bibliotek som `io-ts` eller `zod` kommer till nytta för validering vid körning, vilket vi kommer att diskutera senare.

Använda generiska typer (Generics) för återanvändbara Fetch-funktioner

För att skapa mer återanvändbara fetch-funktioner kan vi använda generiska typer. Generiska typer tillåter oss att definiera en funktion som kan arbeta med olika datatyper utan att behöva skriva separata funktioner för varje typ.

Definiera en generisk Fetch-funktion

            async function fetchData(url: string): Promise {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data: T = await response.json();
  return data;
}

            

              
                Copy
              
            
          

I detta exempel har vi definierat en generisk funktion `fetchData` som tar en typparameter `T`. Funktionen returnerar ett `Promise` som resolverar till ett värde av typen `T`. Vi har också lagt till felhantering för att kontrollera om svaret var framgångsrikt.

Använda den generiska Fetch-funktionen

Nu kan vi använda den generiska `fetchData`-funktionen med olika gränssnitt:

            interface Post {
  id: number;
  title: string;
  body: string;
  userId: number;
}

fetchData('https://jsonplaceholder.typicode.com/posts/1')
  .then(post => {
    console.log(post.title); // Typsäker åtkomst till egenskapen 'title'
  })
  .catch(error => {
      console.error("Error fetching post:", error);
  });

fetchData('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.email);
    });
  })
  .catch(error => {
      console.error("Error fetching users:", error);
  });

            

              
                Copy
              
            
          

I detta exempel använder vi den generiska `fetchData`-funktionen för att hämta både ett enskilt `Post`-objekt och en array av `User`-objekt. TypeScript kommer automatiskt att härleda rätt typ baserat på den typparameter vi tillhandahåller.

Hantera fel och statuskoder

Det är avgörande att hantera fel och statuskoder när man arbetar med Fetch API. Vi kan lägga till felhantering i vår `fetchData`-funktion för att kontrollera för HTTP-fel och kasta ett fel om det behövs.

            async function fetchData(url: string): Promise {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data: T = await response.json();
  return data;
}

            

              
                Copy
              
            
          

I detta uppdaterade exempel kontrollerar vi egenskapen `response.ok`, som indikerar om svarsstatuskoden ligger inom intervallet 200-299. Om svaret inte är OK, kastar vi ett fel med statuskoden.

Datavalidering vid exekvering med `io-ts` eller `zod`

Som nämnts tidigare utför TypeScript-typassertioner (`as`) inte validering vid körning. För att säkerställa att datan som tas emot från API:et faktiskt matchar den förväntade typen kan vi använda bibliotek som `io-ts` eller `zod`.

Använda `io-ts`

`io-ts` är ett bibliotek för att definiera körtidstyper och validera data mot dessa typer.

            import * as t from 'io-ts'
import { PathReporter } from 'io-ts/PathReporter'

const UserType = t.type({
  id: t.number,
  name: t.string,
  email: t.string
})

type User = t.TypeOf

async function fetchDataAndValidate(url: string): Promise {
  const response = await fetch(url)
  const data = await response.json()

  const decodedData = t.array(UserType).decode(data)

  if (decodedData._tag === 'Left') {
    const errors = PathReporter.report(decodedData)
    throw new Error(`Validation errors: ${errors.join('\n')}`)
  }

  return decodedData.right
}


fetchDataAndValidate('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.name);
    });
  })
  .catch(error => {
    console.error('Error fetching and validating users:', error);
  });

            

              
                Copy
              
            
          

I detta exempel definierar vi en `UserType` med `io-ts` som motsvarar vårt `User`-gränssnitt. Vi använder sedan `decode`-metoden för att validera datan som tas emot från API:et. Om valideringen misslyckas kastar vi ett fel med valideringsfelen.

Använda `zod`

`zod` är ett annat populärt bibliotek för schemadeklaration och validering.

            import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer;

async function fetchDataAndValidate(url: string): Promise {
  const response = await fetch(url);
  const data = await response.json();

  const parsedData = z.array(UserSchema).safeParse(data);

  if (!parsedData.success) {
    throw new Error(`Validation errors: ${parsedData.error.message}`);
  }

  return parsedData.data;
}


fetchDataAndValidate('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.name);
    });
  })
  .catch(error => {
    console.error('Error fetching and validating users:', error);
  });

            

              
                Copy
              
            
          

I detta exempel definierar vi ett `UserSchema` med `zod` som motsvarar vårt `User`-gränssnitt. Vi använder sedan `safeParse`-metoden för att validera datan som tas emot från API:et. Om valideringen misslyckas kastar vi ett fel med valideringsfelen.

Både `io-ts` och `zod` erbjuder ett kraftfullt sätt att säkerställa att datan som tas emot från API:er matchar den förväntade typen vid körning.

Integrera med populära ramverk (React, Angular, Vue.js)

Typsäkra Fetch API-anrop kan enkelt integreras med populära JavaScript-ramverk som React, Angular och Vue.js.

React-exempel

            import React, { useState, useEffect } from 'react';

interface User {
  id: number;
  name: string;
  email: string;
}

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function fetchUsers() {
      try {
        const response = await fetch('https://api.example.com/users');
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
        }
        const data: User[] = await response.json();
        setUsers(data);
      } catch (error: any) {
        setError(error.message);
      } finally {
        setLoading(false);
      }
    }

    fetchUsers();
  }, []);

  if (loading) {
    return 
Loading...
;
  }

  if (error) {
    return 
Error: {error}
;
  }

  return (
    

      {users.map(user => (
        
{user.name}
      ))}
    
  );
}

export default UserList;

            

              
                Copy
              
            
          

I detta React-exempel använder vi `useState`-hooken för att hantera tillståndet för `users`-arrayen. Vi använder också `useEffect`-hooken för att hämta användarna från API:et när komponenten monteras. Vi har lagt till typannoteringar till `users`-tillståndet och `data`-variabeln för att säkerställa typsäkerhet.

Angular-exempel

            import { Component, OnInit } from '@angular/core';
import { HttpClient } from '@angular/common/http';

interface User {
  id: number;
  name: string;
  email: string;
}

@Component({
  selector: 'app-user-list',
  template: `
    

      
{{ user.name }}
    
  `,
  styleUrls: []
})
export class UserListComponent implements OnInit {
  users: User[] = [];

  constructor(private http: HttpClient) { }

  ngOnInit() {
    this.http.get('https://api.example.com/users')
      .subscribe(users => {
        this.users = users;
      });
  }
}

            

              
                Copy
              
            
          

I detta Angular-exempel använder vi `HttpClient`-tjänsten för att göra API-anropet. Vi specificerar typen av svaret som `User[]` med hjälp av generiska typer, vilket säkerställer typsäkerhet.

Vue.js-exempel

            



            

              
                Copy
              
            
          

I detta Vue.js-exempel använder vi `ref`-funktionen för att skapa en reaktiv `users`-array. Vi använder `onMounted`-livscykelkroken för att hämta användarna från API:et när komponenten monteras. Vi har lagt till typannoteringar till `users`-referensen och `data`-variabeln för att säkerställa typsäkerhet.

Bästa praxis för typsäkra anrop med Fetch API

Här är några bästa praxis att följa när du implementerar typsäkra Fetch API-anrop i TypeScript:

• Definiera gränssnitt: Definiera alltid gränssnitt som representerar strukturen för den förväntade datan.
• Använd generiska typer: Använd generiska typer för att skapa återanvändbara fetch-funktioner som kan fungera med olika datatyper.
• Hantera fel: Implementera felhantering för att kontrollera HTTP-fel och kasta fel om det behövs.
• Validera data: Använd bibliotek som `io-ts` eller `zod` för att validera datan som tas emot från API:er vid körning.
• Typa ditt state: När du integrerar med ramverk som React, Angular och Vue.js, typa dina state-variabler och API-svar.
• Centralisera API-konfiguration: Skapa en central plats för din API:s bas-URL och eventuella gemensamma headers eller parametrar. Detta gör det lättare att underhålla och uppdatera din API-konfiguration. Överväg att använda miljövariabler för olika miljöer (utveckling, staging, produktion).
• Använd ett API-klientbibliotek (valfritt): Överväg att använda ett API-klientbibliotek som Axios eller en genererad klient från en OpenAPI/Swagger-specifikation. Dessa bibliotek erbjuder ofta inbyggda funktioner för typsäkerhet och kan förenkla dina API-interaktioner.

Sammanfattning

Att implementera typsäkerhet med Fetch API i TypeScript är avgörande för att bygga robusta och underhållbara webbapplikationer. Genom att definiera gränssnitt, använda generiska typer, hantera fel och validera data vid körning kan du avsevärt minska exekveringsfel och förbättra den övergripande utvecklarupplevelsen. Denna guide ger en omfattande översikt över hur man uppnår typsäkerhet med Fetch API, tillsammans med praktiska exempel och bästa praxis. Genom att följa dessa riktlinjer kan du skapa mer tillförlitliga och skalbara webbapplikationer som är lättare att förstå och underhålla.

Vidare utforskning

• Kodgenerering från OpenAPI/Swagger: Utforska verktyg som automatiskt genererar TypeScript API-klienter från OpenAPI/Swagger-specifikationer. Detta kan avsevärt förenkla API-integration och säkerställa typsäkerhet. Exempel inkluderar: `openapi-typescript` och `swagger-codegen`.
• GraphQL med TypeScript: Överväg att använda GraphQL med TypeScript. GraphQL:s starkt typade schema ger utmärkt typsäkerhet och eliminerar överflödig datahämtning (over-fetching).
• Testa typsäkerhet: Skriv enhetstester för att verifiera att dina API-anrop returnerar data av den förväntade typen. Detta hjälper till att säkerställa att dina mekanismer för typsäkerhet fungerar korrekt.